4.7. Updating resources

Calendar entity updates apply changes to a data model which has the form:

• An iCalendar element contains…​

• a single vCalendar element which contains…​

• one or more calendaring components, event, task etc. each of which contain…​

• zero or more components, alarms etc. or one or more properties each of which contains…​

• zero or more parameters and one or more values.

Thus we have a nested structure which does recurse to a limited extent and looks like

<icalendar>
  <vcalendar>
    <components>
      <vevent>
        <properties>
          <uid>
            <text>1302064354993-a</text>
          </uid>
          <summary>
            <text>try this</text>
          </summary>
          <dtstart>
            <date-time>2011-07-18T15:00:00Z</date-time>
          </dtstart>
          <dtend>
            <date-time>2011-07-18T16:00:00Z</date-time>
          </dtend>
        </properties>
      </vevent>
    </components>
  </vcalendar>
</icalendar>

The update approach described here only allows for updating a single calendar entity, though that entity may consist of more than one component, for example an override to a repeating event.

Resources are updated with the CalWS-SOAP updateItem request. The request contains the href of the entity to be updated, the current change token for that entity and the updates. The updates take the form of nested selections of an element from the current level in the data. The outermost selection is always for a vCalendar element — we ignore the iCalendar element. Nested within that outer selection is one for the components element followed by selections on the entity, event, task etc and so on.

Only 3 kinds of update may be applied at any point:

• Remove — components, properties or parameters

• Add — components, properties or parameters

• Change — property or parameter values

Removals MUST be processed ahead of additions.

Preconditions as specified in Preconditions for Calendar Object Creation are applicable. The response will indicate success or failure of the update. If the change token value does not match that held by the service a mismatchedChangeToken error status will be returned. The client should re-fetch the entity to refresh its cache and then retry the update based on the new entity values and change token.

The ComponentsSelectionType contains three repeating child elements. The first allows for selection of nested components which can then be updated. The next allows addition of entire components and the last allows for the removal of components.

The PropertiesSelectionType follows the same pattern, selecting properties to update, add or remove.

To complete that pattern there is also a ParametersSelectionType used to select property parameters for update or removal and to supply new parameters.

Each of these refers to a reference type. These either provide a complete entity for addition or identify the entity for removal. The three reference types are:

To complete the picture we have three selection types for component, property and parameter. Each of these identifies the entity to be updated, possible selections of the sub-elements and a possible change to values.

ComponentSelectionType contains three child elements. The first is any valid iCalendar component element which is to be matched at the current level.

The optional properties selection allows selection and possible updates to the properties of the component. An iCalendar properties element cannot take a value so the only updates possible are addition and removal of properties. Nested properties may be selected for updates.

The optional components selection allows selection and possible updates to the nested iCalendar components element of the component. An iCalendar components element cannot take a value so the only updates possible are addition and removal of components. Nested components may be selected for updates.

PropertySelectionType contains three child elements. The first is any valid iCalendar property element which is to be matched at the current level.

The optional parameters selection allows selection and possible updates to the parameters of the property. The optional change element allows a change to the value of the property. The new value is specified by supplying an iCalendar property with the desired value(s). Any parameters will be ignored.

Lastly, there is the ParameterSelectionType which contains two child elements. The first is any valid iCalendar parameter element which is to be matched at the current level. The optional change element allows a change to the value of the parameter. The new value is specified by supplying an iCalendar parameter with the desired value(s).

For a successful update the service will respond with a UpdateItemResponseType containing the status and the new change token.

The change token value should be used to replace the value held by the client.